Версия: 2.0

Методы API v2

Описание методов API v2 для получения фидов.

Аутентификация

Для вызова методов API необходимо использовать базовый URL https://api.data.rt-solar.ru/api/v2
Аутентификация производится с помощью JWT-токена. Токен должен быть передан в заголовке Authorization по схеме Bearer.

Описание методов API

В API v2 существуют следующие методы, при помощи которых можно получать фиды:
GET /api/v2/feeds/tree - используется для получения дерева доступных для клиента фидов.
GET /api/v2/feeds/{feed-name-by-tree} - используется для получения индикаторов конкретного фида.

Права доступа к фидам для пользователя

Доступ к фидам для пользователя устанавливается на уровне родительских и/или дочерних фидов.
Логика формирования ответа:

Если разрешен родительский фид, то при запросе по родительскому фиду возвращаются индикаторы из родительского и разрешенных дочерних фидов.
Если родительский фид не разрешен, но разрешены его дочерние, то в ответе вернутся индикаторы только из разрешенных дочерних фидов.

Пример 1: Запрос разрешенного родительского фида
Запрос: /4rays_pulse/ (фид разрешен).
Результат: Возвращаются все индикаторы с фидом 4rays_pulse + индикаторы из разрешенных дочерних фидов.
Объяснение: Так как родительский фид разрешен, возвращаются индикаторы разрешенных дочерних фидов.

Пример 2: Запрос запрещенного родительского фида
Запрос: /generic/ (фид generic запрещен, но разрешны несколько дочерних).
Результат: Возвращаются только индикаторы из разрешенных дочерних фидов.
Объяснение: Родительский фид запрещен, поэтому возвращаются только индикаторы из явно разрешенных дочерних фидов.

Получение дерева доступных фидов

Метод API GET /api/v2/feeds/tree используется для получения дерева доступных фидов для клиента, возвращает доступные фиды с учетом иерархии. Выводятся не все, а только доступные для клиента фиды.
Вызывается без параметров.

Пример запроса

curl --location --request GET 'https://api.data.rt-solar.ru/api/v2/feeds/tree' \
--header 'Authorization: Bearer {JWT_TOKEN}'

Пример ответа

В ответе API будет предоставлен список фидов в массиве feeds представленный в древовидной структуре.

{
    "feeds": [
        {
            "name": "4rays_pulse",
            "id": "111306d9-87ea-4027-b865-ad6dfaa70abc",
            "feeds": [
                {
                    "name": "active_c2",
                    "id": "222306d9-87ea-4027-b865-ad6dfaa70abc",
                    "parent_id": "111306d9-87ea-4027-b865-ad6dfaa70abc"
                },
                {
                    "name": "cybercrime",
                    "id": "333306d9-87ea-4027-b865-ad6dfaa70abc",
                    "parent_id": "111306d9-87ea-4027-b865-ad6dfaa70abc",
                    "feeds": [
                        {
                            "name": "honeypot_attacker",
                            "id": "444306d9-87ea-4027-b865-ad6dfaa70abc",
                            "parent_id": "333306d9-87ea-4027-b865-ad6dfaa70abc"
                        }
                    ]
                }
            ]
        },
        {
            "name": "generic",
            "id": "555306d9-87ea-4027-b865-ad6dfaa70abc",
            "feeds": [
                {
                    "name": "apt",
                    "id": "666306d9-87ea-4027-b865-ad6dfaa70abc",
                    "parent_id": "555306d9-87ea-4027-b865-ad6dfaa70abc"
                }
            ]
        },
        {
            "name": "fincert",
            "id": "777306d9-87ea-4027-b865-ad6dfaa70abc"
        }
    ]
}

Описание ответа

В ответе API представляются данные в формате JSON.

№	Поле	Тип данных	Описание	Пример
1	name	string	Название фида	"name": "active_c2"
2	id	string	UUID фида	"id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b"
3	feeds	array(string)	Массив дочерних фидов. Заполняется только для дочерних фидов	{ "feeds": [ { "name": "generic", "id": "555306d9-87ea-4027-b865-ad6dfaa70abc", "feeds": [ { "name": "apt", "id": "666306d9-87ea-4027-b865-ad6dfaa70abc", "parent_id": "555306d9-87ea-4027-b865-ad6dfaa70abc" } ] } ] }
4	parent_id	string	UUID родительского фида. Заполняется только для дочерних фидов	"parent_id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b"

Получение индикаторов конкретного фида

Метод API GET /api/v2/feeds/{feed-name-by-tree} используется для получения индикаторов конкретного фида.
В обязательном параметре feed-name-by-tree передается название фида (пути, источники данных), из которого запрашиваются индикаторы.
Примеры параметра feed-name-by-tree:

/4rays_pulse
/4rays_pulse/active_c2
/4rays_pulse/cybercrime
/4rays_pulse/cybercrime/backdoor

При вызове метода API GET /api/v2/feeds без параметров вернутся все индикаторы из доступных пользователю фидов.

Пример запроса

curl --location --request GET 'https://api.data.rt-solar.ru/api/v2/feeds/4rays_pulse' \
--header 'Authorization: Bearer {JWT_TOKEN}'

Пример запроса без параметров

curl --location --request GET 'https://api.data.rt-solar.ru/api/v2/feeds' \
--header 'Authorization: Bearer {JWT_TOKEN}'

Параметры запроса

№	Параметр	Тип данных	Обязательность	Описание	Варианты значений
1	updated_at	string	нет	В данном параметре передается дата и время (с указанием микросекунд) создания или обновления индикатора в формате ISO с точностью до микросекунд Если значение параметра отсутствует, то поиск будет производиться по всем индикаторам без фильтрации по времени Если параметр указан, запрос вернёт не более `limit` индикаторов, отсортированных в порядке, заданном в `direction_sort`: При `direction_sort=ASC` будут выбраны индикаторы, чья дата создания или обновления больше указанного значения (от старых к новым). При `direction_sort=DESC` будут выбраны индикаторы, чья дата создания или обновления меньше указанного значения (от новых к старым).	2022-10-26T17:30:00.000001Z
2	actions	string	нет	В данном параметре передается состояние индикатора, который нужно вернуть в ответе Если значение отсутствует, то поиск будет производиться по всем полям При передаче параметра может быть указано несколько значений через запятую	Допустимые значения: CREATE UPDATE DELETE
3	fields	string	нет	В данном параметре передается список полей, которые вернутся в ответе Если значение отсутствует, то поиск будет производиться по всем полям При передаче параметра может быть указано несколько значений через запятую Если в запросе в параметре fields передано невалидное значение, то будет возвращена ошибка с кодом 400. Обязательные значения ответа: updated_at	Допустимые значения: id type value description created_at updated_at first_seen last_seen zone categories feeds attributes contexts related_objects network file cve
4	limit	int	нет	Данный параметр ограничивает число записей, которые возвращаются в ответе. Значение по умолчанию - 100, максимальное значение - 1000	100
5	direction_sort	string	нет	Задает направление сортировки и итерации. При ASC порядок индикаторов в ответе отсортирован по возрастанию, при DESC — по убыванию (от новых к старым).	Допустимые значения: ASC DESC
6	indicator_types	array(string)	да	Типы индикатора	Допустимые значения: IPV4 SOCKETV4 IPV6 SOCKETV6 URL DOMAIN MD5 SHA1 SHA256

Пример ответа

API возвращает массив объектов, каждый из которых содержит полную информацию об индикаторе компрометации (IoC). Ниже представлен пример одного элемента массива с подробными комментариями к ключевым полям:

[
  {
  "id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b",
  "type": "IPV4",
  "value": "192.0.2.100",
  "description": "описание",
  "created_at": "2022-10-26T17:30:00.000001Z",
  "updated_at": "2022-10-26T17:30:00.000001Z",
  "first_seen": "2022-10-26T17:30:00.000001Z",
  "last_seen": "2022-10-26T17:30:00.000001Z",
  "zone": "MALICIOUS",
  "cve": "CVE-2021-44228, CVE-2018-20580",
  "categories": [
    "malicious"
  ],
  "feeds": [
    {
      "name": "4rays_pulse",
      "action": "create",
      "valid_until": "2022-10-26T17:30:00.000001Z",
      "feeds": [
        {
          "name": "c2",
          "action": "create",
          "valid_until": "2025-10-26T17:30:00.000001Z"
        }
      ]
    }
  ],
  "attributes": {
    "key": "value"
  },
  "contexts": [
    {
      "source_name": "whois",
      "attributes": {
        "nameservers": "ns1.example-domain.net",
        "registrar": "EXAMPLE-REGISTRAR-RU"       
      }
    }
  ],
  "related_objects": [
    {
      "id": "cf830e6d-addc-4983-8c38-906ef5fb6457",
      "type": "IPV4",
      "value": "203.0.113.50"
    },
    {
      "id": "12330e6d-addc-4983-8c38-906ef5fb6457",
      "type": "threat_actor",
      "value": "Example Threat Actor",
      "ttps": [
        {
            "mitre_id": "T1134",
            "mitre_url": "https://attack.mitre.org/techniques/T1134/"
        },
        {
            "mitre_id": "T1134.001",
            "mitre_url": "https://attack.mitre.org/techniques/T1134/001/"
        }
    ]
    }  
  ],
  "network": {
    "heuristics": [
      {
        "risk_level": "CRITICAL",
        "description": "У индикатора обнаружены признаки вредоносной активности, соответствующей его категории"
      }
    ]
  },
  "file": {
    "verdicts": ["YARA:Nix.HackTool.3snake.1a"],
    "os": "Nix",
    "size": 207232,
    "file_identifiers": ["php-fpm"],
    "mime": "application/x-sharedlib",
    "malware_family": ["nix.hacktool.3snake.1a"],
    "hashes": {
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
    }
  }
},
{
  "..."
}
]

Описание ответа

В ответе API предоставляется массив объектов в формате JSON.

№	Поле	Тип данных	Описание	Варианты значений	Пример
1	id	string	UUID индикатора	-	"id": "421da453-5f3b-4542-b8fe-099f7d9cbe2b"
2	type	string	Тип индикатора	IPV4, IPV6, SOCKETV4, SOCKETV6, URL, DOMAIN, MD5, SHA1, SHA256	"type": "IPV4"
3	value	string	Значение индикатора	-	"value": "5.8.95.174"
4	description	string	Описание индикатора	-	"description": "IP dangerous"
5	created_at	string	Дата и время создания индикатора	-	"created_at": "2022-10-26T17:30:00.000001Z"
6	updated_at	string	Дата и время совершения изменений для индикатора	-	"updated_at": "2022-10-26T17:30:00.000001Z"
7	first_seen	string	Дата и время первого обнаружения индикатора	-	"first_seen": "2022-10-26T17:30:00.000001Z"
8	last_seen	string	Дата и время последнего обнаружения индикатора	-	"last_seen": "2022-10-26T17:30:00.000001Z"
9	zone	string	Определяет уровень критичности угрозы и позволяет классифицировать индикаторы по степени потенциальной опасности.	Описание поля zone	"zone": "MALICIOUS"
10	categories	array (string)	Категории индикатора	malicious, spam, phishing, c2, malware, etc.	"categories": ["spam"]
11	feeds	array (object)	Массив объектов с информацией о фидах. Каждый объект содержит: name - название фида action - действие valid_until - срок валидности индикатора feeds - вложенный массив фидов	action: CREATE, UPDATE, DELETE	{ "feeds": [ { "name": "4rays_pulse", "action": "create", "valid_until": "2022-10-26T17:30:00.000001Z", "feeds": [ { "name": "c2", "action": "create", "valid_until": "2022-10-26T17:30:00.000001Z" } ] } ] }
12	attributes	object	Дополнительные атрибуты индикатора в формате ключ-значение	Содержит произвольные пары ключ-значение для хранения дополнительной информации	"attributes": {"key": "value"}
13	contexts	array (object)	Контекстная информация об индикаторе из различных источников. Каждый объект содержит: source_name - название источника attributes - атрибуты контекста	Описание источников и их атрибутов	"contexts": [ { "source_name": "whois", "attributes": { "nameservers": "ns1.timeweb.org", "registrar": "RU-CENTER-RU" } }, { "source_name": "ipapi", "attributes": { "hosting_facility": "Example Hosting", "isp": "Example ISP", "asn": "AS12345" } } ]
14	related_objects	array (object)	Массив связанных объектов с их идентификаторами, типами и значениями.	Каждый объект содержит: • id: UUID связанного объекта • type: тип связанного объекта • value: значение связанного объекта Объект типа threat_actor так же может содержать дополнительное поле ttps - связанные тактики, техники и процедуры (TTPs)	"related_objects": [ { "id": "cf830e6d-addc-4983-8c38-906ef5fb6457", "type": "IPV4", "value": "95.119.184.232" }, { "id": "12330e6d-addc-4983-8c38-906ef5fb6457", "type": "threat_actor", "value": "Shedding Zmiy", "ttps": [ { "mitre_id": "T1134", "mitre_url": "https://attack.mitre.org/techniques/T1134/" }, { "mitre_id": "T1134.001", "mitre_url": "https://attack.mitre.org/techniques/T1134/001/" } ] } ]
15	network	object	Сетевая информация об индикаторе.	Описание поля heuristics	{ "network": { "heuristics": [ { "risk_level": "HIGH", "description": "Suspicious Network Behavior - обнаружены множественные подключения к недоверенным хостам в короткий промежуток времени" } ] } }
16	file	object	Информация о файле (для файловых индикаторов).	Описание поля file	{ "file": { "verdicts": ["YARA:Nix.HackTool.3snake.1a"], "os": "Nix", "size": 207232, "file_identifiers": ["php-fpm"], "mime": "application/x-sharedlib", "malware_family": ["nix.hacktool.3snake.1a"], "hashes": { "md5": "11160afc0a8606b67c1eec4c39fd94fe", "sha1": "111d7440595261b4ecfe43d797a6a06a3a5654f4" } } }
17	cve	array(string)	Связанные с индикатором уязвимости	-	"cve": ["CVE-2021-44228", "CVE-2018-20580"]

Возможные значения поля zone

API v1	API v2	Описание
BLACK	MALICIOUS	Индикатор с высокой степенью достоверности связан с подтверждённой вредоносной активностью (malware, C2, фишинг, эксплуатация уязвимостей и т. п.). Рекомендуемые действия: немедленное блокирование, приоритизация инцидента, проведение детального расследования и поиск связанных артефактов.
GREY	SUSPICIOUS	Индикатор демонстрирует признаки потенциально вредоносной активности, однако подтверждённых доказательств недостаточно для однозначной классификации. Рекомендуемые действия: дополнительный анализ, корреляция с телеметрией и другими источниками, усиленный мониторинг.
WHITE	CLEAN	На основании имеющихся данных индикатор относится к легитимной активности и не связан с вредоносными действиями на текущий момент. Рекомендуемые действия: использование в качестве allowlist / контекста, без применения ограничительных мер.
NEUTRAL	UNKNOWN	Недостаточно информации для оценки индикатора и определения его связи с вредоносной или легитимной активностью. Рекомендуемые действия: наблюдение, обогащение данными из внешних и внутренних источников.

Контекстная информация об индикаторе из различных источников

Это необязательный набор данных, который может присутствовать для обогащения индикаторов дополнительными сведениями.

Каждый объект контекста contexts содержит:

source_name - название источника данных
attributes - атрибуты контекста в формате ключ-значение

Возможные источники source_name и их атрибуты attributes:

1. Источник: ipapi

hosting_facility - хостинг-провайдер
is_tor - является ли TOR-нодой
is_crawler - является ли сканирующим сервисом
is_proxy - является ли прокси-сервисом
isp - интернет-провайдер
asn - номер автономной системы
country - геопозиция хоста

2. Источник: whois

nameservers - DNS-серверы домена
creation - дата создания домена
expiration - дата истечения регистрации домена
registrar - регистратор домена

3. Источник: fstec

id - идентификатор записи
date - дата публикации информации
summary - краткое описание, содержащее номер бюллетеня

Важно: Наличие конкретных источников и атрибутов зависит от типа индикатора и доступности данных в момент обогащения.

Описание поля heuristics

Эвристика — результирующее правило или алгоритм, который на основе анализа данных и признаков формирует вероятностную оценку или классификацию объекта/события.
Результат работы эвристики
Результатом работы эвристики является автоматически сгенерированное заключение, которое:

Классифицирует объект по заданным категориям (например: "безопасный", "подозрительный", "вредоносный")
Формулирует текстовое описание выявленных признаков и рисков

Пример:

"heuristics": [
{
  "risk_level": "HIGH",
  "description": "Suspicious Network Behavior - обнаружены множественные подключения к недоверенным хостам в короткий промежуток времени"
}
]

№	Поле	Тип данных	Описание	Допустимые значения	Пример
1	risk_level	string	Уровень риска	CRITICAL HIGH MEDIUM DECREASE SAFE INFO	"risk_level": "CRITICAL"
2	description	string	Описание эвристики	-	"description": "Обнаружена подозрительная сетевая активность"

Описание поля file

№	Поле	Тип данных	Описание	Пример
1	verdicts	array(string)	Вердикт анализа файла	"verdicts": ["malicious"]
2	os	string	Целевая операционная система, может принимать следующие значения: WIN, NIX, MAC, CROSS, ANDROID	"os": "WIN"
3	size	int	Размер файла	"size": 207232
4	file_identifiers	array(string)	Имена и пути файла	"file_identifiers": ["PE32 executable"]
5	mime	string	MIME-тип файла	"mime": "application/x-dosexec"
6	malware_family	array(string)	Информация о вредоносности	"malware_family": ["Trojan.Win32.Generic"]
7	hashes	object	Объект в котором содержатся недостающие хеши файла (при наличии файла). Допустимые значения: md5 sha1 sha256	{ "hashes": { "md5": "d41d8cd98f00b204e9800998ecf8427e", "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709" } } или { "hashes": { "md5": "d41d8cd98f00b204e9800998ecf8427e", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } }

Аутентификация​

Описание методов API​

Права доступа к фидам для пользователя​

Получение дерева доступных фидов​

Пример запроса​

Пример ответа​

Описание ответа​

Получение индикаторов конкретного фида​

Пример запроса​

Пример запроса без параметров​

Параметры запроса​

Пример ответа​

Описание ответа​

Возможные значения поля zone​

Контекстная информация об индикаторе из различных источников​

Описание поля heuristics​

Описание поля file​

Аутентификация

Описание методов API

Права доступа к фидам для пользователя

Получение дерева доступных фидов

Пример запроса

Пример ответа

Описание ответа

Получение индикаторов конкретного фида

Пример запроса

Пример запроса без параметров

Параметры запроса

Пример ответа

Описание ответа

Возможные значения поля zone

Контекстная информация об индикаторе из различных источников

Описание поля heuristics

Описание поля file